OpenAPI3.xでの仕様書の書き方

OpenAPI3.xでの仕様書の書き方を記載します。

#OpenAPI

#Swagger

serina

2024.07.26

SBJソリューション部のserinaです。
先日、OpenAPIで仕様書を作成する機会がありました。

つまずいた点が何個かあったので書き方をまとめておきたいと思います。

バージョン

バージョン： OpenAPI 3.0.3
作成ファイル形式： yml
（UIツール： Swagger UI）

作成したパス構造

src/
│
├── paths/
│
├── responses/
│
├── schemas/
│
└── index.yml

paths ... APIの定義ファイルを格納
responses ... レスポンスの定義ファイルを格納
schemas ... スキーマの定義ファイルを格納
index.yml ... 他のファイルを呼び出すメインファイル

書き方

決まった値が入る場合はenumを定義

ステータスなどのプロパティで0か1など、決まった値が入る場合は、enumで定義しておくことができます。

status:
  type: integer
  enum: [0, 1]

type: integerの場合はformatを定義できる

status:
  type: integer
  format: int64

定義できるformatは、このパターンになります。

type	format
number	–
number	float
number	double
integer	–
integer	int32
integer	int64

最小・最大値はminLengthとmaxLengthを使用

date:
  type: string
  minLength: 8
  maxLength: 8

正規表現はpatternで定義

yyyyMMdd形式など、決まった形式がある場合はpatterに定義します。

date:
  type: string
  pattern: '^\d{4}(0[1-9]|1[0-2])(0[1-9]|[12]\d|3[01])$'

共通化して呼び出したい

共通化したい箇所は、$refを使用することで参照可能です。

paths:
  /users/{id}:
    get:
      summary: Gets a user by ID.
      response:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '401':
          $ref: '#/components/responses/Unauthorized'   # <-----
        '404':
          $ref: '#/components/responses/NotFound'       # <-----

# Descriptions of common components
components:
  responses:
    NotFound:
      description: The specified resource was not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    # Schema for error response body
    Error:
      type: object
      properties:
        code:
          type: string
        message:
          type: string
      required:
        - code
        - message

descriptionを別で記載したいときは、responsesではなくschemasに定義して呼び出します。

パスの指定の仕方

$ref: '#/components/schemas/User'

# の前にファイルパスがない場合は、現在のファイル内の参照という意味になります。

$ref: './schemas/user.yml#/User'

# の前の ./schemas/user.yml は参照先のファイルパスで、
# 以降の /User は、そのファイル内の User を呼び出しています。

一部だけ参照したい

参照したい箇所とインラインで書きたい箇所が混在している場合は、allOfを使用します。

schemaを＄ref参照し、exampleは別で定義したい

responses:
  '200':
    description: OK
    content:
      application/json:
        schema:
          allOf:
            - $ref: '#/components/schemas/User'
            - type: object
              example:
                id: abcde12345

例が複数ある場合は複数形のexamplesを使う

responses:
  '200':
    description: OK
    content:
      application/json:
        schema:
          allOf:
            - $ref: '#/components/schemas/User'
            - type: object
        examples:
          example1:
            summary: First example
            value:
              id: abc123
          example2:
            summary: Second example
            value:
              id: 321cba

$ref参照して一部を上書き

参照する箇所としない箇所が混在し、かつ、一部上書きしたい場合はこう書きます。

responsesのdescriptionを上書き

responses:
  '403':
    allOf:
      - $ref: '#/components/schemas/User'
    description: 403 Forbidden

parametersのexampleを上書き

parameters:
  - allOf:
    - $ref: '#/components/schemas/User'
    - example: xyz987

個人的につまずいた点や気づいた点

allOfの使い方
exampleとexamplesを書く階層の違い
再利用したい定義は別ファイルで定義して呼び出す方がすっきりと書ける

参考

最後に

初めて書いたので慣れないうちは時間かかったのですが、慣れるとサクサク書いていけました！

工夫次第でもっとシンプルでわかりやすい構造で書いていけるのではないかなと思います。